home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / plug-ins / perl / Gimp / Data.pm < prev    next >
Encoding:
Perl POD Document  |  2003-01-14  |  2.9 KB  |  128 lines
  1. package Gimp::Data;
  2.  
  3. sub freeze($) {
  4.    my $data = shift;
  5.    if (ref $data
  6.        or $data =~ /^\$VAR1 = \[/) {
  7.       if ( eval { require Data::Dumper } ) {
  8.          $data = new Data::Dumper [$data];
  9.          $data->Purity(1)->Terse(0);
  10.          return $data->Dump;
  11.       } else {
  12.          return;
  13.       }
  14.    }
  15.    $data;
  16. }
  17.  
  18. sub thaw {
  19.    my $data = shift;
  20.    if ($data =~ /^\$VAR1 = \[/) {
  21.       if (eval { require Data::Dumper }) {
  22.          my $VAR1; # Data::Dumper is braindamaged
  23.          local $^W=0; # perl -w is braindamaged
  24.          return eval $data;
  25.       } else {
  26.          return;
  27.       }
  28.    }
  29.    $data;
  30. }
  31.  
  32. sub TIEHASH {
  33.    my $pkg = shift;
  34.    my $self;
  35.  
  36.    bless \$self, $pkg;
  37. }
  38.  
  39. sub FETCH {
  40.    thaw eval { Gimp->parasite_find ($_[1])->data }
  41.         || ($@ ? Gimp->get_data ($_[1]) : ());
  42. }
  43.      
  44. sub STORE {
  45.    my $data = freeze $_[2];
  46.    eval { Gimp->parasite_attach ([$_[1], Gimp::PARASITE_PERSISTENT, $data]) };
  47.    Gimp->set_data ($_[1], $data) if $@;
  48. }
  49.  
  50. sub EXISTS {
  51.    $_[0]->FETCH ? 1 : ();
  52. }
  53.      
  54. tie (%Gimp::Data, 'Gimp::Data');
  55.  
  56. 1;
  57. __END__
  58.  
  59. =head1 NAME
  60.  
  61. Gimp::Data - Set and get state data.
  62.  
  63. =head1 SYNOPSIS
  64.  
  65.   use Gimp::Data;
  66.   
  67.   $Gimp::Data{'value1'} = "Hello";
  68.   print $Gimp::Data{'value1'},", World!!\n";
  69.  
  70. =head1 DESCRIPTION
  71.  
  72. With this module, you can access plugin-specific (or global) data in Gimp,
  73. i.e. you can store and retrieve values that are stored in the main Gimp
  74. application.
  75.  
  76. An example would be to save parameter values in Gimp, so that on subsequent
  77. invocations of your plug-in, the user does not have to set all parameter
  78. values again (L<Gimp::Fu> does this already).
  79.  
  80. =head1 %Gimp::Data
  81.  
  82. You can store and retrieve anything you like in this hash. It's contents
  83. will automatically be stored in Gimp, and can be accessed in later
  84. invocations of your plug-in. Be aware that other plug-ins store data
  85. in the same "hash", so better prefix your key with something unique,
  86. like your plug-in's name. As an example, the Gimp::Fu module uses
  87. "function_name/_fu_data" to store its data.
  88.  
  89. This module might use a persistant implementation, i.e. your data might
  90. survive a restart of the Gimp application, but you cannot count on this.
  91.  
  92. C<Gimp::Data> will try to freeze your data when you pass in a reference. On
  93. retrieval, the data is thawed again. See L<Storable> for more info. This
  94. might be implemented through either Storable or Data::Dumper, or not
  95. implemented at all (i.e. silently fail) ;)
  96.  
  97. =head1 PERSISTANCE
  98.  
  99. C<Gimp::Data> contains the following functions to ease applications where
  100. persistence for perl data structures is required:
  101.  
  102. =over 4
  103.  
  104. =item Gimp::Data::freeze(reference)
  105.  
  106. Freeze (serialize) the reference.
  107.  
  108. =item Gimp::Data::thaw(data)
  109.  
  110. Thaw (unserialize) the dsata and return the original reference.
  111.  
  112. =back
  113.  
  114. =head1 LIMITATIONS
  115.  
  116. You cannot store references, and you cannot (yet) iterate through the keys
  117. (with C<keys>, C<values> or C<each>).
  118.  
  119. =head1 AUTHOR
  120.  
  121. Marc Lehmann <pcg@goof.com>
  122.  
  123. =head1 SEE ALSO
  124.  
  125. perl(1), L<Gimp>.
  126.  
  127. =cut
  128.